Documentation

#' @title Specifications For RStudio Conf 2020 Success
#' @section Last updated by:
#' Ellis Hughes
#' @section Last updated date:
#' 2020/01/29
#' 
+ _Specifications_
  + 1.1 Presentation must explain validation procedure.
  + 1.2 Be entertaining by causing 3 laughter sessions.
  + 1.3 Inform and document each step necessary for success.
  + 1.4 (Optional) Fame and Glamour and start branded accessories chain.

Modular Specifications

• Easily shift and update
• De-couple Specifications

Getting Down to Business

• Define function requirements
• Document first approach
• Assign Tasks

Supporting Cast

• Roxygen Documentation
  • Standard Roclets: what, where, why, how
  • ‘Unique’ Validation Roclets: who, when
• Unit Testing

Teamwork and SCM

• Branching
• Detailed code Review
  • Style guides

Documentation

#' @title Deliver Jokes
#' @description 
#'    Deliver jokes with punchlines. Wait 3 seconds for the punchline.
#' @param Setup Joke setup
#' @param Punchline Joke punchline
#' @example
#' joke('To the person who stole my presentation -','I hope you do not Excel.')
#'      
#' @section Last updated by:
#' Ellis Hughes
#' @section Last updated date:
#' 2020/01/29
#' 
#' @export
joke <- function(Setup, Punchline){
  print(Setup)
  Sys.sleep(3)
  print(Punchline)
}

Modular Function Documentation

• Track Progress
• Meet Regularly to discuss roadblocks
• Ensure high quality code

Purpose

• Draw connections between specifications and code

• Show that Code satisfied Specifications

  

The Approach

• Detail Task and Steps
• No Code
• Describe how do all the pieces actually work together

Documentation

#' @title RStudio Conf 2020 Success Test Cases 001
#' @section Last updated by: 
#' Ellis Hughes
#' @section Last update date:
#' 2020/01/29

+ _Test Cases_

+ Setup: Create RStudio::Conf 2020 Presentation 
  
+ T 1.1 Test that specifications 1.2, 1.2, and 1.3 by practicing presentation on unsuspecting co-workers

  - Present to a captive audience of coworkers and later your significant other
  +  T 1.1.1 Test that the presentation was informative by asking what your audience learned.
  +  T 1.1.2 Test that you were entertaining by counting the amount of chuckles (>3)
      + T 1.1.2.1 Alternatively, groans from your significant other at your jokes (>4)

Modular Test Case Documentation

• Easily shift and update
• Easily assign Test Cases
• Track updates

Benefits

• Resolves interpretation errors
  • documentation
  • test cases
• Identify improvements

Approach

• testthat format

• Combine with Roxygen comments

Documentation

context('RStudio Conf 2020 Success')

#' @title RStudio Conf 2020 Success 
#' @section Last updated by: 
#' Ellis Hughes
#' @section Last update date:
#' 2020/01/29
#' 
testthat('T1.1',{
  
  joke_result <- joke('What do you call a fake noodle?','An Impasta')
  expect_true(is_dad_joke(joke_result))
  expect_true(caused_laugher(joke_result))
  expect_true(embarrased_offspring(joke_result))
  
})

Evaluation

• testthat reporter object is created
  • success of expectations as ‘As Expected’
  • failures with the code that fails

Modular Test Code Documentation

• Easily update Test Code and expectations
• Track updates

What we have so far

• Documents for each Specification in markdown
• Roxygen documentation for Code
• Documents for Test Cases in markdown
• Test Case Code augmented with Roxygen documentation

Master Document that

• Record all elements in a single location

• Scraping for Author and Edit Dates

• Separating out specs into files allows for modular extension

• Roxygen to document editing and edit dates

• Testthat to evaluate and record test case code results

EXAMPLE OF PDF

Many thanks to all involved

• Marie Vendettuoli
• Anthony Williams
• Jimmy Fulp
• Bharathi Lakshminarayanan
• Alicia Sato
• Shannon Grant
• Paul Stutzman
• Kate Ostbye